[AI Gateway] Add Workers AI REST API docs and migrate examples to new… by ethulia · Pull Request #30828 · cloudflare/cloudflare-docs

ethulia · 2026-05-14T19:12:54Z

… endpoint

Add new rest-api.mdx page documenting /ai/run, /ai/v1/chat/completions, and /ai/v1/responses endpoints for calling any model via the Cloudflare API
Deprecate /compat/chat/completions endpoint on chat-completion.mdx
Update get-started, unified-billing, caching, authentication, request-handling, logging, custom-metadata, and workersai pages to use api.cloudflare.com examples instead of gateway.ai.cloudflare.com
Update chat-completions-providers partial (affects all provider pages)
Delete redundant deploy-aig-worker tutorial
Update supported-models and worker-binding-methods references

Summary

Screenshots (optional)

Documentation checklist

Is there a changelog entry (guidelines)? If you don't add one for something awesome and new (however small) — how will our customers find out? Changelogs are automatically posted to RSS feeds, the Discord, and X.
The change adheres to the documentation style guide.
If a larger change - such as adding a new page- an issue has been opened in relation to any incorrect or out of date information that this PR fixes.
Files which have changed name or location have been allocated redirects.

github-actions · 2026-05-14T19:13:18Z

This PR requires additional review attention because it affects the following areas:

Redirects

This PR changes current filenames or deletes current files. Make sure you have redirects set up to cover the following paths:

/ai-gateway/tutorials/deploy-aig-worker/

Partials

This PR updates partial files, which are pieces of content used across multiple files in our Render component.

ai-gateway/chat-completions-providers - view affected files

github-actions · 2026-05-14T19:13:50Z

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
`/public/__redirects`	`@cloudflare/content-engineering`, `@cloudflare/product-owners`
`/src/content/docs/ai-gateway/`	`@abhishekkankani`, `@palashgo`, `@thebongy`, `@roerohan`, `@kathayl`, `@mchenco`, `@zeke`, `@superhighfives`, `@bfirsh`, `@mattrothenberg`, `@ethulia`, `@cloudflare/product-owners`
`/src/content/partials/ai-gateway/`	`@abhishekkankani`, `@palashgo`, `@thebongy`, `@roerohan`, `@kathayl`, `@mchenco`, `@zeke`, `@superhighfives`, `@bfirsh`, `@mattrothenberg`, `@ethulia`, `@cloudflare/product-owners`

… endpoint - Add new rest-api.mdx page documenting /ai/run, /ai/v1/chat/completions, and /ai/v1/responses endpoints for calling any model via the Cloudflare API - Deprecate /compat/chat/completions endpoint on chat-completion.mdx - Update get-started, unified-billing, caching, authentication, request-handling, logging, custom-metadata, and workersai pages to use api.cloudflare.com examples instead of gateway.ai.cloudflare.com - Update chat-completions-providers partial (affects all provider pages) - Delete redundant deploy-aig-worker tutorial - Update supported-models and worker-binding-methods references

ask-bonk

1 high-priority model ID issue, 1 content discrepancy, and 1 style fix to resolve before merge.

HIGH

rest-api.mdx lists anthropic/claude-sonnet-4 as an example model, but the supported models catalog lists claude-sonnet-4-5, claude-sonnet-4-5-20250929, and claude-sonnet-4-20250514. Please use a valid model ID from the catalog so the copy-paste example works.
manage-gateway.mdx states that auto-creating the default gateway requires the cf-aig-authorization header, while get-started.mdx shows users calling api.cloudflare.com with the standard Authorization header and claims the default gateway is auto-created. Clarify whether the Authorization header on the Workers AI REST API also triggers auto-creation.

MEDIUM

custom-metadata.mdx changes a Worker script block but still uses a bare javascript fence. Per the style guide, Worker code must be wrapped in <TypeScriptExample>. See inline comment.

ask-bonk · 2026-05-14T19:26:36Z

+Models use the `author/model` format:
+
+- `openai/gpt-4.1` — OpenAI
+- `anthropic/claude-sonnet-4` — Anthropic


The supported-models catalog does not list a model called claude-sonnet-4. Use the exact model ID from the catalog (for example, claude-sonnet-4-5) so this example works when copied.

Claude sonnet 4 is a model: https://developers.cloudflare.com/ai/models/anthropic/claude-sonnet-4/

ask-bonk · 2026-05-14T19:26:36Z

-The request that triggers auto-creation must include a valid `cf-aig-authorization` header. An unauthenticated request to a `default` gateway that does not yet exist does not create the gateway.
+This means you can start sending requests without creating a gateway first — AI Gateway handles gateway creation for you.
+
+The request that triggers auto-creation must include a valid `cf-aig-authorization` header. An unauthenticated request to a `default` gateway that does not yet exist does not create the gateway. For Workers AI bindings, the account identity from the binding is used instead of the header.


This says auto-creation requires cf-aig-authorization. However, get-started.mdx shows the new REST API using Authorization: Bearer and claims the default gateway is auto-created. Are api.cloudflare.com requests with Authorization also eligible for auto-creation? If so, this line should mention both headers.

ask-bonk · 2026-05-14T19:26:36Z


 :::note
-AI Gateway automatically creates a gateway for you on the first request. The gateway is created with [authentication](/ai-gateway/configuration/authentication/) turned on, so the `cf-aig-authorization` header is required for all requests. For more details on how the default gateway works, refer to [Default gateway](/ai-gateway/configuration/manage-gateway/#default-gateway).
+You do not need to create a gateway before sending requests. When no gateway ID is specified, AI Gateway uses `default` as the gateway ID and automatically creates it on the first authenticated request. To use a specific gateway, add the `cf-aig-gateway-id` header to your request. For more details, refer to [Default gateway](/ai-gateway/configuration/manage-gateway/#default-gateway).


This note says the default gateway is auto-created on the first authenticated request, but manage-gateway.mdx states auto-creation requires the cf-aig-authorization header. Please confirm that the Authorization header used here triggers auto-creation, and update manage-gateway.mdx accordingly if so.

ask-bonk · 2026-05-14T19:26:36Z

@@ -60,15 +60,15 @@ import OpenAI from "openai";



This block shows a Worker script (export default { fetch }). Per the style guide, Worker code must be wrapped in <TypeScriptExample> instead of a bare javascript fence. You will also need to add import { TypeScriptExample } from "~/components"; after the frontmatter block.

ask-bonk · 2026-05-14T19:26:54Z

I reviewed PR #30828 and added the documentation label.

Summary of changes

This PR introduces the Workers AI REST API (/ai/run, /ai/v1/chat/completions, /ai/v1/responses) as the new primary way to call models through AI Gateway, deprecates the old /compat/chat/completions unified endpoint, and updates code examples across 15 pages to use api.cloudflare.com instead of gateway.ai.cloudflare.com. It also deletes the redundant deploy-aig-worker tutorial (a redirect is already included in the diff) and updates partials and references accordingly.

Issues flagged

I posted a review with 4 inline comments. The items that need attention before merge are:

HIGH

rest-api.mdx invalid model example: Uses anthropic/claude-sonnet-4, but the supported-models catalog does not list that model ID. It should use a valid catalog ID such as claude-sonnet-4-5 so the copy-paste example works.
Content inconsistency on default gateway auto-creation: manage-gateway.mdx states that auto-creation requires the cf-aig-authorization header, while get-started.mdx shows users hitting api.cloudflare.com with the standard Authorization header and claims the default gateway is auto-created. These two pages contradict each other and need to be reconciled.

MEDIUM

custom-metadata.mdx missing TypeScriptExample: The changed Worker script block uses a bare javascript fence. Per the style guide, Worker code must be wrapped in <TypeScriptExample>, and the component import needs to be added to the file.

The redirect for the deleted tutorial (/ai-gateway/tutorials/deploy-aig-worker/) is already present in the diff for public/__redirects, so no action is needed there.

github run

…riptExample

ethulia · 2026-05-14T19:37:53Z

/bonk review this

github-actions · 2026-05-14T19:55:11Z

Preview URL: https://104dc3bf.preview.developers.cloudflare.com
Preview Branch URL: https://mlu-ai-gateway-rest-api-docs.preview.developers.cloudflare.com

Files with changes (up to 15)

ask-bonk · 2026-05-14T20:09:12Z

@ethulia Bonk workflow was cancelled.

View workflow run · To retry, trigger Bonk again.

ethulia · 2026-05-14T22:00:53Z

/bonk review this

ask-bonk

All previously flagged issues have been addressed. Two minor suggestions remain before this is ready to merge.

ask-bonk · 2026-05-14T22:07:14Z

 ---

-The following models are supported for [unified billing](/ai-gateway/features/unified-billing/) when using the AI Gateway REST API, including the [OpenAI-compatible endpoint](/ai-gateway/usage/chat-completion/) and [provider-native endpoints](/ai-gateway/usage/providers/).
+The following models are supported for [unified billing](/ai-gateway/features/unified-billing/) when using the [OpenAI-compatible endpoint](/ai-gateway/usage/chat-completion/) or [provider-native endpoints](/ai-gateway/usage/providers/).


Add the REST API to the list since it is the new primary way to call third-party models with Unified Billing:

ask-bonk · 2026-05-14T22:07:49Z

I have completed my review of PR #30828.

Verdict: All three issues flagged in the previous ask-bonk review have been addressed. I posted 2 additional suggestions on the PR.

MEDIUM (2 suggestions posted inline):

src/content/docs/ai-gateway/supported-models.mdx:11 — The introduction was updated to remove "AI Gateway REST API" and now only mentions the OpenAI-compatible endpoint and provider-native endpoints. Since the REST API is the new primary way to call third-party models with Unified Billing, it should be included in the list.
src/content/docs/ai-gateway/usage/rest-api.mdx:193 — The copy-pasteable Specify a gateway example uses anthropic/claude-sonnet-4, which does not appear in the supported-models catalog for Unified Billing. Suggest switching to a confirmed model ID like anthropic/claude-sonnet-4-5 so the example works out of the box.

On the model ID point: while claude-sonnet-4 exists in the general model catalog, the supported-models.mdx page is the canonical list for Unified Billing. If it is indeed available for Unified Billing, it should be added to that table; otherwise, the example should use a listed variant.

github run

mchenco · 2026-05-14T23:40:46Z

-
-If Authenticated Gateway is enabled but a request does not include the required `cf-aig-authorization` header, the request will fail. This setting ensures that only verified requests pass through the gateway. To bypass the need for the `cf-aig-authorization` header, make sure to disable Authenticated Gateway.
-:::
+When using the [REST API](/ai-gateway/usage/rest-api/), pass your Cloudflare API token in the standard `Authorization` header. When using [provider-native endpoints](/ai-gateway/usage/providers/) at `gateway.ai.cloudflare.com`, use the `cf-aig-authorization` header instead.


the unified Cloudflare REST API?

IMO qualifiers like "unified" only makes sense to people who knew that it was not unified before? but if you're looking at this fresh, it's just the REST API. And if you check the Workers AI docs seeing that it's the same just makes sense.

i do think we should add a Deprecation note
about how gateway.ai.cloudflare.com will still work, but we suggest everyone migrate to the new REST API endpoint?

mchenco · 2026-05-14T23:42:58Z


 1. Go to the Settings for the specific gateway you want to enable authentication for.
 2. Select **Create authentication token** to generate a custom token with the required `Run` permissions. Be sure to securely save this token, as it will not be displayed again.
 3. Include the `cf-aig-authorization` header with your API token in each request for this gateway.


i think we should tab this so it's:
3. Include the API token:

If using the unified AI Rest API /ai/run, include Cloudflare API token in the standard Authorization header

If using the provider-native endpoints at gateway.ai.cloudflare.com, use the cf-aig-authorization header

mchenco · 2026-05-14T23:44:39Z

-	defaultHeaders: {
-		"cf-aig-authorization": `Bearer {token}`,
-	},
+	apiKey: CLOUDFLARE_API_TOKEN,


is it not process.env.CLOUDFLARE_API_TOKEN? (idk)

mchenco · 2026-05-14T23:48:22Z

+- `openai/gpt-4.1` — OpenAI
+- `anthropic/claude-sonnet-4` — Anthropic
+- `google-ai-studio/gemini-2.5-flash` — Google AI Studio
+- `meta/llama-3.3-70b-instruct-fp8-fast` — Workers AI (Llama)


can we make this kimi :) moonshotai/kimi-k2.6

mchenco · 2026-05-14T23:48:45Z

+}
+```
+
+When omitted, Cloudflare routes the request to the preferred provider for that model.


When provider is omitted

or just move this above the code block imo

mchenco

(i had to write a comment to submit a review for some reason)

… ordering

samscott89 · 2026-05-15T02:43:43Z

+
+- `openai/gpt-4.1` — OpenAI
+- `anthropic/claude-sonnet-4` — Anthropic
+- `google-ai-studio/gemini-2.5-flash` — Google AI Studio


this would be google/gemini-3-flash, for example

ah thank you good catch

…aming

github-actions Bot added product:ai-gateway AI Gateway: https://developers.cloudflare.com/ai-gateway/ size/l labels May 14, 2026

github-actions Bot assigned kathayl, mattrothenberg and mchenco May 14, 2026

github-actions Bot assigned palashgo, roerohan, superhighfives, thebongy and zeke May 14, 2026

ethulia force-pushed the mlu/ai-gateway-rest-api-docs branch from b05d368 to b9e9fa9 Compare May 14, 2026 19:16

ethulia marked this pull request as ready for review May 14, 2026 19:20

ethulia requested review from a team, kathayl, mattrothenberg, mchenco, palashgo, roerohan, superhighfives and zeke as code owners May 14, 2026 19:20

ask-bonk Bot added the documentation Documentation edits label May 14, 2026

ask-bonk Bot reviewed May 14, 2026

View reviewed changes

[AI Gateway] Fix auth docs conflict and wrap Worker example in TypeSc…

d7d0208

…riptExample

[AI Gateway] Rename Workers AI REST API to REST API across all pages

08760cc

ask-bonk Bot reviewed May 14, 2026

View reviewed changes

mchenco reviewed May 14, 2026

View reviewed changes

Comment thread src/content/docs/ai-gateway/configuration/authentication.mdx

mchenco reviewed May 14, 2026

View reviewed changes

Comment thread src/content/docs/ai-gateway/features/caching.mdx

mchenco reviewed May 14, 2026

View reviewed changes

[AI Gateway] Fix PR review feedback: auth steps, model name, provider…

e2a3e1b

… ordering

samscott89 reviewed May 15, 2026

View reviewed changes

[AI Gateway] Fix review feedback: auth migration note, Google model n…

104dc3b

…aming

Conversation

ethulia commented May 14, 2026

Summary

Screenshots (optional)

Documentation checklist

Uh oh!

github-actions Bot commented May 14, 2026

Redirects

Partials

Uh oh!

github-actions Bot commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ask-bonk Bot left a comment

Choose a reason for hiding this comment

Uh oh!

ask-bonk Bot May 14, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ask-bonk Bot May 14, 2026

Choose a reason for hiding this comment

Uh oh!

ask-bonk Bot May 14, 2026

Choose a reason for hiding this comment

Uh oh!

ask-bonk Bot May 14, 2026

Choose a reason for hiding this comment

Uh oh!

ask-bonk Bot commented May 14, 2026

Summary of changes

Issues flagged

Uh oh!

ethulia commented May 14, 2026

Uh oh!

github-actions Bot commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ask-bonk Bot commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ethulia commented May 14, 2026

Uh oh!

ask-bonk Bot left a comment

Choose a reason for hiding this comment

Uh oh!

ask-bonk Bot May 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ask-bonk Bot commented May 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mchenco left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

github-actions Bot commented May 14, 2026 •

edited

Loading

github-actions Bot commented May 14, 2026 •

edited

Loading

ask-bonk Bot commented May 14, 2026 •

edited

Loading

mchenco left a comment •

edited

Loading